SharePoint 2010 : The Client Object Model (part 1) - Infrastructural Objects, Object Identity

There are numerous ways to get data out of SharePoint. One of those ways is WCF services (including the old time ASMXs). However, out of the box WCF services provide you with a limited API. You can author your own WCF services, but a rather interesting out of the box WCF service in SharePoint 2010, is available at /_vti_bin/client.svc. This client.svc service is your entry point to the client object model.

But what is the client object model? SharePoint comes with a rich API with various objects such as SPSite, SPWeb, SPList, and so on. All these objects have proven very effective in interacting with SharePoint sites and data. However, modern day applications use plenty of client-side technologies such as Ajax and Silverlight. Also there is an emergence of distributed applications in which the application consuming SharePoint data may not be running on the SharePoint server. The client object model provides you with a client-side API that mimics a large portion of the server-side API. This client-side API can be called from regular .NET applications, Silverlight applications, or Ajax applications using JavaScript. The best way to understand the client-side object model is to look at examples of each of these. However before we dive into specific examples, it is important to understand some basics first.

I should point out that even though I'm describing the client object model using WebParts as examples, the client object model is something that is not limited to just WebParts. You can use this in any part of SharePoint or even outside of SharePoint in regular .NET applications!

1. Client Object Model Design

The client object model has been designed with two things in mind

• It is as similar as possible to the server-side model. This eliminates a serious learning curve.

• It is designed in to give you, the developer, full control on when the round trips to the server are made, and what data is loaded when those round trips are made.

When I say that the client object model has been designed to be as similar as possible, Table 1 makes that absolutely clear.

If you are familiar with the server object model, you should have no problem picking up the client object model. Besides the similarities, there are some notable differences as well. For instance, the client object model does not provide any objects scoped higher than SPSite. Also the various administration-related objects are missing in the client object model. Also, the querying semantics in the client object model are somewhat different because when working with the client object model, you are always dealing with a distributed application. The objects shown in Table 5-1 are also referred to as ClientObjects because all of them inherit from a ClientObject base class. There are also base classes in the framework to represent collections of such ClientObjects. There is however a whole other category of objects in the client object model called infrastructural objects.

2. Infrastructural Objects

The SharePoint 2010 client object model uses several objects to transfer data between the server and client. When I say transfer data between the server and client, I do not mean an object that represents the site or web. Instead I am referring to objects that will help you fill and interact with other objects that represent the site or web. The objects that represent site or web are called ClientObjects. Infrastructural objects let you fill and persist ClientObjects.

Perhaps the most important infrastructural object is the ClientContext object. The process of working with the server from the client starts with the ClientContext object. It is best to understand the usage of ClientContext with a very simple example. I'm going to write a simple console application that retrieves the title of the site using the client object model.

Start by opening Visual Studio 2010, and create a simple console application targeting .NET framework 3.5. Call it COMHelloWorld. Next go ahead and add references to the Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll. You can find these assemblies in the 14\ISAPI folder. Next, edit your console application to include the code shown in Listing 1.

Example 1. HelloWorld Client Object Model Code

static void Main(string[] args)
{
  string siteUrl = "http://sp2010";
  using (ClientContext myContext = new ClientContext(siteUrl))
  {
    myContext.Load(myContext.Site);
    myContext.ExecuteQuery();
    Console.WriteLine(myContext.Site.Url);
  }
}

Now if you run your console application, you will note that your console application can successfully read the title of your site. But this code looks slightly different from the regular server-side code. For starters, there is a ClientContext object, which seems to act as the central policeman in the client object model. The process of obtaining and working with sites and data in the client object model begins by retrieving a ClientContext object.

The second interesting thing is a ClientContext.Load method. In your console application, if you were to comment out the Load and ExecuteQuery statements, and then try and access site.Url, you would get a PropertyOrFieldNotInitializedException.

The Load method allows you to specify to the ClientContext what you're interested in retrieving. But it isn't until you execute the ExecuteQuery method that the object is actually retrieved. Another method similar to Load is the LoadQuery method.

Now, comment out the Console.WriteLine statement and replace it with the code shown following:

foreach (List list in myContext.Web.Lists)
{
  Console.WriteLine(list.Title);
}

If you were to run the preceding code, you would get CollectionNotInitializedException. However if you were to edit your Load statement to look like the following, your code would then run just fine:

myContext.Load(myContext.Web,
web => web.Lists.Include(list => list.Title).Where(field => field.Hidden == false));

					  

Thus the ExecuteQuery method only loads what you specify to be loaded in the Load method (or the LoadQuery method, as you will see shortly). In the previous line of code, you are only loading titles of lists that are visible.

The above code will work, but the syntax is not a pleasure to read. There is yet another way for you to specify what you wish to have loaded from SharePoint: the LoadQuery method. Go ahead and modify your console application code to look like Listing 2. Note that the code in Listing 5-2 still needs to be between the using statements you see in Listing 1.

Example 2. Client Object Model Using the LoadQuery Method

var query = from list in myContext.Web.Lists
     where list.Hidden != false
     select list;

var lists = myContext.LoadQuery(query);
myContext.ExecuteQuery();

foreach (var list in lists)
{
  Console.WriteLine(list.Title);
}

As you can see, the code shown in Listing 5-2 is much easier to read. Also the object loaded is an object in itself; it is not a property of ClientContext. You still need to call ClientContext.ExecuteQuery in order to load such an object.

If you were to run the code shown in Listing 2, you would still see that many properties are not evaluated. In debug mode, trying to access those properties will give you a PropertyOrFieldNotInitializedException or a CollectionNotInitializedException.

Other than the Load and LoadQuery methods, yet another way of loading data using the client object model is by using object prototypes, which allow you to specify the data to be retrieved for an object even if the object hasn't been retrieved yet. This is extremely useful when you're trying to save on the number of roundtrips executed to the server. This same scenario, can also be achieved by using the LoadQuery method.

As an example, suppose that you want to retrieve all views of a list, but you don't have a viable list object yet. Usually you would first have to get a list object and then execute a second round trip to get its views! Wouldn't it be nice to get all this information in a single roundtrip? Prototypes solve that problem. Observe the code shown in Listing 3. This code fetches the various lists and views in the lists. Using the Retrieve method, you specify the specific object you wish to have retrieved, but in a single ExecuteQuery (round trip to the server), you are able to fill the information necessary.

Example 3. Prototype-based Code to Fetch Lists and List Views in One Round Trip

ClientOobjectPrototype<List> listProtoype =
  myContext.Web.Lists.RetrieveItems();
ClientObjectCollectionPrototype<View> viewProtoType =
  listProtoype.RetrieveCollectionObject<View>(ListObjectPropertyNames.Views);

					  

viewProtoType.RetrieveItems().Retrieve();
listProtoype.Retrieve();

myContext.ExecuteQuery();

foreach (var list in myContext.Web.Lists)
{
  Console.WriteLine("The views in list: " + list.Title);
  foreach (View view in list.Views)
  {
    Console.WriteLine(view.Title);
  }
}

If you were to select the ClientObjectPrototype object in Visual Studio and press F12 to examine the metadata for this object, you would see something like this:

[EditorBrowsable(EditorBrowsableState.Never)]
public ClientObjectPrototype<T> RetrieveItems();

By doing so, Microsoft is intentionally hiding these objects from you and is discouraging their use. The .Retrieve and .RetrieveItems methods are not intended to be used by developers. Instead, developers should use LINQ -based semantics, which are the .Load and .LoadQuery methods.

Besides just fetching data from SharePoint, note that the client object model will also let you update data back to the SharePoint server. Updating data raises a whole new set of challenges, however. One such relevant concept is a concept of object identity.

3. Object Identity

When you work with simple objects in .NET code, you access them through variables. When two variables hold a reference to the same object, editing the data from one variable would immediately reflect the changes in the other variable.

Objects that are inherently tied to a central data store such as SharePoint, or even a database server, cannot work under this behavior. This is because their identity is constrained by their unique identifiers in the central store (in this case, SharePoint), and the main issue is that objects when being modified as variables are now disconnected from the actual store they live in; they are now being modified on the client.

Thus, the data that would then be queried out of the same items in the SharePoint server will probably not correspond to the same object instances your client object model represents.

This discrepancy is resolved by having the ClientContext manage object identities. Whenever an object is retrieved from SharePoint, its identity is remembered by its unique identifier. Whenever the same object is retrieved again, the original object instance is handed back to the application running the client object model. This way, the ClientContext translates SharePoint's concept of identities (unique identifier or GUID) into .NET language's concepts (object instances). This way, the application consuming the object model sees the object only in the state it was first retrieved. If newer data is encountered, it is discarded.

New data is discarded? That cannot possibly be good, right? Well, no; it really isn't as bad as it sounds. If you were writing an application, you would expect the data in your objects to remain the same until you persist the changes back to the SharePoint server. If in the meantime some other user has modified the same data you were working with, the client object model will give you a concurrency exception. But the whole idea here is that your business logic gets the same data it expects to get your business logic will not get confused by data magically changing under the carpet because of other user's actions until you try and issue an update, at which point optimistic concurrency checks are performed.

This process of ensuring the identity of retrieved objects across multiple retrieves between updates is referred to as the concept of object identity.

3.1. Updating Data Using the Client Object Model

Updating data from the client object model is rather simple. The following code snippet updates the title of the site:

myContext.Load(myContext.Web);
myContext.ExecuteQuery();
myContext.Web.Title = "New title";
myContext.Web.Update();
myContext.ExecuteQuery();

Adding a new list or a new list item requires you to create a ClientObjectCreationInformation object or a class that inherits from that. The word "ClientObject" is important in the client object model because ClientObject is an abstract base class from which most client objects, such as SPList and SPWeb in the Microsoft.SharePoint.Client namespace, inherit from. Thus ClientObjectCollection is the abstract base class for most client object collection–like objects. And ClientObjectCreationInformation is the abstract base class for classes such as ListCreationInformation.

The code shown in Listing 4 adds a new list into your site.

Example 4. Adding a New List into SharePoint Using the Client Object Model

// Add a new list into the SharePoint site.
List newlyAddedList = myContext.Web.Lists.Add(
  new ListCreationInformation()
  {
    Title = "A New List",
    Description = "Some Description",
    TemplateType = (int) ListTemplateType.Announcements
  }
  );
newlyAddedList.Update();
myContext.ExecuteQuery();

This covers the basic theory of the client object model. All the code snippets you saw were in pure .NET-managed code. But perhaps the best feature of the client object model is that it is also accessible from Silverlight and JavaScript.

Next, let us solidify our understanding of the client object model by building an interesting application that uses both Silverlight and JavaScript. What I intend to build here is a Silverlight WebPart that shows calendar information from a list based on the calendar list template in SharePoint. I will use the client object model to display the information in a visually appealing way. To make the WebPart visually appealing and also to demonstrate the integration with third-party products, I will integrate the client object model with popular third-party products such as telerik's Silverlight suite. This suite is freely downloadable for trial purposes, but you are more than welcome to use the same concepts for any Silverlight front end. For your convenience I have included a non-telerik version of the described code sample in the associated code download as well.

I will also write another WebPart that uses JavaScript as its main execution engine. Using JavaScript I will also consume the client object model. Specifically, given the ID of the list item I will use the ClientObject model from JavaScript to load the details of that list item.

Finally I will make these two WebParts, the Silverlight WebPart and the JavaScript WebPart, talk to each other using WebPart connections. What will be different this time around, however, is that the two WebParts when communicating with each other will communicate purely on the client side. They will not cause postbacks. In short, I intend to do the following: